TableLib v1.0
by Klarth (stevemonaco@hotmail.com)
December 30, 2006

I.   Overview
II.  Table Features
III. Library Usage
IV.  Sample Programs



I. Overview
     TableLib is a set of C++ classes that can be used in C++ programs (or at your own efforts, put into a DLL wrapper to
use it in other languages) that support table reading and encoding/decoding using a table.

     This a revision of my personal table library made to be better than it was before, but it's not as well-tested honestly since I'm
stretched for time.  I've only tested it on Mother 3 (custom dumper/inserter) and Final Fantasy 1 (sample utilities),
whereas the old version was used in many dumpers and inserters, including Atlas.  The bulk of the code is the same, so it should be fine.



II. Table Features
      TableLib supports a slightly different feature set than most other programs.
      - Supports virtually unlimited hex and string lengths, as long as the hex strings are whole bytes.
        0123456789=super long string here <-- This is fine, the hex string represents 5 whole bytes.
        01234=another long string <-- Error, the hex string is 2.5 bytes.
      - The same table can be used for both insertion and dumping, TableReader accomodates for the changes.
      - Ability to add newline characters for dumping.  They will be ignored during insertion.
        /FF=<END>\n\n <-- This is how you should define your endtokens so the library functions properly
      - *FE or *FE=<LINE>\n <-- Newline values are useless, but still supported.
        FE=<LINE>\n <-- Preferred way to define a line break.
      - The so-called "linked entry" from Thingy terminology, but implemented a bit better.  This allows you to
        dump control codes that have parameter bytes cleanly, without it being dumped as text.
        $0500=<Color>,1 <-- Dumps 0500 as <Color> and dumping one parameter byte afterwards as a <$XX> hex entry.
      - Skips entries such as:
        !F0 <-- Dakuten control code isn't supported
        @F1 <-- Handakuten control code isn't supported
        {80000h-dump-e.txt}Block1 <-- Insertion Bookmarks are skipped
        [28210h-2B495h]Block1 <-- Dump Bookmarks are skipped



III. Library Usage

       The library was developed using VC++ 2005 Pro, a prior version before a rewrite supposedly had bugs with g++ but
       I don't use g++ so I didn't test it.  If you don't have a copy of VC++, then you can download a free copy of
       Visual C++ 2005 Express Edition at http://msdn.microsoft.com/vstudio/express/visualc/
       You'll want to create a Console Application or Win32 Project, unless you want to wander into the realm of MC++. *shudder*

       Insertion
       - Include TableReader.cpp, TableReader.h, TableEncoder.cpp, TableEncoder.h in your project
       - Declare an instance of TableEncoder
         TableEncoder Inserter;
       - Open the table and check return code
         Inserter.OpenTable("yourgame.tbl");
       - Read the data to be encoded into a string, this can be a single string or a whole dialogue block
       - Encode the data and check return code for -1 (missing table entry error)
         Inserter.EncodeString(TextData, BadCharOffset)
       - Iterate the TableEncoder::StringTable, where your hex strings are to be written to the game
         for(TblStringListIt i = Inserter.StringTable.begin(); i != Inserter.StringTable.end(); i++)
         {
             // Write i->Text.c_str() to the game here
         }

       Dumping
       - Include TableReader.cpp, TableReader.h, TableDecoder.cpp, TableDecoder.h in your project
       - Declare an instance of TableDecoder
         TableDecoder Dumper;
       - Open the table and check return code
         Dumper.OpenTable("yourgame.tbl");
       - Read the data to be decoded into an unsigned char array or vector<unsigned char>
       - Loop with TableDecoder::DecodeString until it returns 0 (no more left to decode)
         while((len = Dumper.DecodeString(TextString, EndString)) != 0)
         {
             // Dump TextString to your script, EndString is required to be the same as the EndString value in the table
             // This is so the dumper will know which EndString value to check to decode one string at a time, if this is
             // different from your table, then it will dump the whole script in one go, which is bad when you need more control
         }



IV. Sample Programs

      Included are two sample programs with source that are your average run-of-the-mill dumper and insertion programs.  They're fully
functional, simple programs that can dump text by offset or insert a script at an offset without pointer rewriting.  Sample code for
approximately how you'd add pointer rewriting is in the source.  Dumping by pointers is just a matter of calculating a pointer, reading
a string into a buffer (you have to deal with getting the length), and decoding it.

      Inserter usage:
        Inserter ROM.ext Script.txt Table.tbl StartOffset(hex)

      Dumper usage:
        Dumper ROM.ext Table.tbl StartOffset(hex) EndOffset(hex) Output.txt